Skip to content

docs: drop openssl-tpm2-engine in favor of PKCS#11 - #538

Merged
tashian merged 2 commits into
mainfrom
docs/remove-openssl-tpm2-engine
Jul 29, 2026
Merged

docs: drop openssl-tpm2-engine in favor of PKCS#11#538
tashian merged 2 commits into
mainfrom
docs/remove-openssl-tpm2-engine

Conversation

@joshdrake

@joshdrake joshdrake commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

Closes EFF-473.

Why

The Ubuntu install step told readers to apt-get install step-agent openssl-tpm2-engine, and the agent's PKCS#11 section opened by pointing them at OpenSSL's tpm2-openssl provider / libtpm2-tss as the integration path. Neither matches how the agent actually works.

Verified against origin/main of smallstep/agent:

  • openssl-tpm2-engine was never a step-agent package dependency. git log -S across all refs returns zero hits; the string appears nowhere in the agent repo. The docs line has been advisory since it was added in Nov 2024, and nothing ever consumed it.
  • The Linux packages declare PKCS#11 deps instead (.goreleaser.yml): deb → p11-kit, p11-kit-modules, libengine-pkcs11-openssl; rpm → p11-kit, openssl-pkcs11. Only Arch/Nix declare tpm2-openssl, which is the tpm2-software provider — a different project from openssl-tpm2-engine.
  • All agent-driven network auth moved to the built-in PKCS#11 server — smallstep/agent#1056 ("Always use pkcs11 server with network manager") and smallstep/agent#1072 ("Use pkcs11 for EAPoL on Linux").

What changed

  • Ubuntu install — drop openssl-tpm2-engine, making the step identical to Debian's.
  • Rename OpenSSL and PKCS#11 support → PKCS#11 support, and lead with the PKCS#11 server as the supported integration point for NetworkManager, wpa_supplicant, VPN clients, and browsers.
  • Document the auto-registered p11-kit module. The Linux packages install /etc/pkcs11/modules/step-agent.module (agent v0.67.4+), so p11-kit-aware software needs no manual setup. NSS apps (Chrome, Firefox) still need the modutil step, which is called out explicitly.
  • Fix the socket path in all 5 places. It is /run/step-agent/step-agent-pkcs11.sock, not $XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock. extra/step-agent.service hard-sets RUNTIME_DIRECTORY=/run/step-agent, and extra/step-agent.module, extra/wpa_supplicant-step-agent.conf, and pkg/pkcs11server/README.md all independently agree. The old path was wrong even in the user-session fallback, which joins the filename directly to $XDG_RUNTIME_DIR with no step-agent subdirectory.
  • Update the two troubleshooting links to the renamed #pkcs11-support anchor.

No manifest.json change and no redirect needed — the page URL is unchanged, only an in-page anchor moved.

Verification

  • grep confirms zero remaining openssl-tpm2-engine, openssl-and-pkcs11-support, or $XDG_RUNTIME_DIR/step-agent in any .mdx.
  • Vale output is byte-identical before and after (5 errors, 3 warnings, all pre-existing on untouched lines).
  • Anchors validated against github-slugger, the same slugger rehype-slug uses on the site: PKCS#11 support → pkcs11-support. Cross-checked the rule against two existing working links. All 8 inbound anchors to smallstep-agent.mdx resolve.

Notes for the reviewer

  • Conflicts with docs/pkcs11-modutil-order (unmerged), which rewrites the same section to reorder export P11_KIT_SERVER_ADDRESS before modutil -add. I deliberately did not duplicate that fix — whichever lands second should resolve.
  • The section is scoped to Linux on purpose. macOS resolves to a different socket path and integrates via CryptoTokenKit; nothing in the agent tree consumes the macOS socket, so I did not document it.

Out of scope, worth follow-ups

  • packages.smallstep.com/containers/Dockerfile.ubuntu:13 still runs apt-get -y install step-agent-plugin openssl-tpm2-engine step-cli — stale on two counts, since the current package name is step-agent. The debian/fedora/centos sibling Dockerfiles don't install it.
  • smallstep/openssl_tpm2_engine's debian/control has the wrong Homepage/Vcs-Git (points at tpm2-software/tpm2-openssl, a different project).
  • 11 pre-existing broken cross-file anchors elsewhere in the docs (step-ca/, certificate-manager/), surfaced by the anchor check I ran. Untouched here.

🤖 Generated with Claude Code

https://claude.ai/code/session_012CzzkgZ1fM8x5AdmMFhE6v

@joshdrake @claude
docs: drop openssl-tpm2-engine in favor of PKCS#11
fd4f027 
The Ubuntu install step told readers to install `openssl-tpm2-engine`
alongside step-agent, and the agent's PKCS#11 section opened by pointing
them at OpenSSL's `tpm2-openssl` provider / `libtpm2-tss`. Neither
reflects how the agent works.

`openssl-tpm2-engine` was never a step-agent package dependency -- the
string appears nowhere in the agent repo, in any ref. The Linux packages
declare PKCS#11 deps instead (deb: p11-kit, p11-kit-modules,
libengine-pkcs11-openssl; rpm: p11-kit, openssl-pkcs11), and all
agent-driven network auth moved to the built-in PKCS#11 server in
smallstep/agent#1056 and #1072.

- Ubuntu install: drop the package, matching the Debian step.
- Rename "OpenSSL and PKCS#11 support" to "PKCS#11 support" and lead with
  the PKCS#11 server as the supported integration point.
- Document the auto-registered p11-kit module
  (/etc/pkcs11/modules/step-agent.module, agent v0.67.4+), and note that
  NSS apps still need the manual modutil step.
- Fix the socket path in all five places: it is
  /run/step-agent/step-agent-pkcs11.sock, not
  $XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock. The shipped unit
  hard-sets RUNTIME_DIRECTORY=/run/step-agent, and step-agent.module,
  wpa_supplicant-step-agent.conf, and pkg/pkcs11server/README.md all
  agree.
- Update the two troubleshooting links to the renamed anchor.

Refs EFF-473

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012CzzkgZ1fM8x5AdmMFhE6v
@CLAassistant

CLAassistant commented Jul 27, 2026

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@joshdrake
joshdrake marked this pull request as ready for review July 27, 2026 17:03
@joshdrake
joshdrake requested a review from a team as a code owner July 27, 2026 17:03
@joshdrake @claude
Merge origin/main into docs/remove-openssl-tpm2-engine
8d38d7a 
Resolves the conflict with #534 (docs/pkcs11-modutil-order), which
rewrote the same PKCS#11 section.

Kept #534's contribution intact: the reordered Chrome recipe (export
P11_KIT_SERVER_ADDRESS before modutil -add, single bash fence), its
warning Alert, and the new "Recovering from a failed modutil add"
troubleshooting subsection.

Carried this branch's fixes forward onto that new text:

- smallstep-agent.mdx: dropped this branch's now-redundant trailing
  export (superseded by #534 moving it to the top of the fence) and
  corrected the surviving export to /run/step-agent/step-agent-pkcs11.sock.
- troubleshooting-agent.mdx: #534's new subsection merged without a
  conflict marker but carried two regressions against this branch --
  a link to the renamed #openssl-and-pkcs11-support anchor, and a
  fourth instance of the wrong $XDG_RUNTIME_DIR socket path. Both fixed.

Verified: zero occurrences of openssl-tpm2-engine,
openssl-and-pkcs11-support, or XDG_RUNTIME_DIR/step-agent remain; vale
output is identical to origin/main for both files; #pkcs11-support,
#recovering-from-a-failed-modutil-add, and
#pkcs11-not-working-linuxmacos all resolve.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012CzzkgZ1fM8x5AdmMFhE6v
@joshdrake

joshdrake commented Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

Merged main to resolve the conflict with #534

#534 (docs/pkcs11-modutil-order) landed on main first and rewrote the same PKCS#11 section, so this branch resolves. #534's work is kept intact — the reordered Chrome recipe (export P11_KIT_SERVER_ADDRESS before modutil -add, single bash fence), its warning <Alert>, and the new "Recovering from a failed modutil add" troubleshooting subsection all carry forward.

What I changed on top:

smallstep-agent.mdx — the one real conflict. #534 moved the export to the top of the fence, making this branch's trailing export redundant; dropped it and corrected the surviving line to /run/step-agent/step-agent-pkcs11.sock.

troubleshooting-agent.mdx — worth flagging: #534's new subsection merged with no conflict marker, but carried two regressions against this branch that a plain git merge --continue would have shipped silently:

  1. A link to #openssl-and-pkcs11-support — the anchor this PR renames, so it would have 404'd within the same page pair.
  2. A fourth instance of the $XDG_RUNTIME_DIR/step-agent/... socket path.

Both fixed. Net: main had grown to 6 wrong socket paths and 3 stale anchor refs (from 5 and 2), so this PR now clears one more of each than originally described.

Verification after the merge

  • Zero remaining openssl-tpm2-engine, openssl-and-pkcs11-support, or XDG_RUNTIME_DIR/step-agent in any .mdx; zero stray conflict markers.
  • Vale output is byte-identical to origin/main for both files (5 errors, 3 warnings, all pre-existing on untouched lines) — diffed against a baseline run, not eyeballed.
  • Anchors re-validated with github-slugger: #pkcs11-support, #recovering-from-a-failed-modutil-add (docs: fix modutil/P11_KIT_SERVER_ADDRESS ordering in PKCS#11 guide #534's new one), and #pkcs11-not-working-linuxmacos all resolve. Repo-wide sweep: 70 cross-file anchor links, 11 broken — all pre-existing in step-ca/ and certificate-manager/, none in platform/.
  • CI: Lint Prose and both markdown-link-check runs pass.

@tashian
tashian merged commit 89ad214 into main Jul 29, 2026
3 of 4 checks passed
@tashian
tashian deleted the docs/remove-openssl-tpm2-engine branch July 29, 2026 23:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tashian tashian tashian approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@joshdrake @CLAassistant @tashian